<html>
<head>
  <title>How to build the ocamldoc tool</title>
</head>

<body>
<h2>How to build the ocamldoc tool</h2>

<p><a href="http://pauillac.inria.fr/~guesdon/tools.html">ocamldoc</a>
is a tool for extracting documentation from specially-formatted
comments in the source code.  It works similarly to
<a href="http://java.sun.com/j2se/javadoc/index.html">javadoc</a>.
The following instructions explain how to get, build, and use this tool,
especially in the context of the CCured project.</p>

<p>For the purposes of these instructions, pick some directories:</p>
<ul><li><tt>$DIST</tt>: directory where you'll download the tarballs
        (e.g. <tt>/home/scott/dist</tt>)
    <li><tt>$BLD</tt>: directory where you'll compile the software
        (e.g. <tt>/home/scott/bld</tt>)
    <li><tt>$PREFIX</tt>: directory into which the compiled files will be installed
        (e.g. <tt>/home/scott/lib/ocaml-current</tt> or <tt>/usr/local</tt>)
    <li><tt>$CIL</tt>: toplevel directory of ccured ("cil") repository
        (e.g. <tt>/home/scott/wrk/safec/cil</tt>)
</ul>

<p>First, download and build the latest <a href="http://www.cvshome.org/docs/manual/cvs.html">
CVS</a> snapshot of the <a href="http://caml.inria.fr/ocaml/">OCaml</a> compiler:
<pre>
  % cd $BLD
  % cvs -d :pserver:anoncvs@camlcvs.inria.fr:/caml checkout ocaml
  % cd ocaml
  % ./configure --prefix $PREFIX
  % make world
  % make opt
  % make ocamlc.opt         # ocamldoc wants this?
  % make install
</pre></p>

<p>Next, download the <a href="http://pauillac.inria.fr/~guesdon/Tars/ocamldoc_08_10_2001.tar.gz">
ocamldoc distribution tarball</a>, and build it:
<pre>
  % cd $BLD
  % tar xvfz $DIST/ocamldoc_08_10_2001.tar.gz
  % cd ocamldoc
  % ln -s $BLD/ocaml ocaml
  % patch -p1 < $CIL/doc/ocamldoc.patch     # fix configure.in
  % PATH=$PREFIX/bin:$PATH                  # for sh/bash
      or
  % set path = ($PREFIX/bin $path)          # for csh/tcsh
  % autoconf
  % ./configure                             # inherits --prefix from above
  % make depend
  % make all
  (fails with complaint about either missing .cmx (if ocamlc.opt not built)
  or "inconsistent assumptions over implementation Odoc_misc", but this
  doesn't matter since it makes 'odoc' successfully)
  % make install
  (succeeds in copying 'odoc' to $PREFIX/bin, but fails to copy odoc_info.cma; ignoring)
</pre>
The resulting <tt>odoc</tt> binary can be copied anywhere and used.  However,
it contains within it the path to the 'ocamlrun' binary in $PREFIX/bin, so
that has to stay put.  Building <tt>odoc.opt</tt> unfortunately fails.</p>

<p>(optional) Staying in <tt>$BLD/ocamldoc</tt>, we can have it
generate a few sample documentation files:
<pre>
  % make doctest          # build docs of ocamldoc sources -&gt; doctest/
  % make stdlib           # build docs of ocaml library sources -&gt; stdlib/
  (appears to fail with "Unbound module Support", but actually succeeds)
</pre></p>


<p>Finally, we can use this to generate documentation for the CCured sources:
<pre>
  % cd $CIL
  % make                  # need the .cmi files built
  % make odoc
</pre>
This will dump a bunch of .html files into the odoc/ directory.  It also may spew
some messages about errors parsing text inside comments; those messages are
nonfatal but should be addressed.</p>

<hr>
<p>Originally written by <a href="mailto:smcpeak@cs.berkeley.edu">Scott</a>.

</body>
</html>
